home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / amok98-106 / amok104 / deutsch / poster < prev    next >
Text File  |  1994-05-10  |  10KB  |  215 lines
  1. ===========================================================================
  2.                      AMOK - Amiga Modula & Oberon Klub
  3.  
  4.             "Poster": Norm bzw. Standardform für AMOK-Beiträge
  5.                Tips und Anhaltspunkte für Veröffentlichungen
  6. ===========================================================================
  7.  
  8. Einleitung
  9.  
  10. Wir   -AMOK-   sind  gerne  bereit,  auch  anderen  Modula-2-  bzw.  Oberon-
  11. Programmierern  mit  den  AMOK-Disks  einen  Weg  zur Veröffentlichung Ihrer
  12. Programme  zu  bieten.  Ziel  unserer  PD-Reihe ist es schließlich, für eine
  13. möglichst  weite  Verbreitung  von  Modula & Oberon zu sorgen. Da sich diese
  14. Programmiersprachen  optimal zum Austausch von Programm-Modulen eignen, kann
  15. jeder Programmierer hierzu beitragen. Je größer die Modulbibliothek ist, auf
  16. die  ein  Programmierer  zurückgreifen  kann,  desto weniger muß er sich mit
  17. zeitraubenden  Alltagsproblemen herumschlagen und sozusagen "das Rad zweimal
  18. erfinden".  Falls  Sie  also Module geschrieben haben, von denen Sie denken,
  19. daß auch andere sie gebrauchen können, schicken Sie sie an AMOK. Wenn irgend
  20. möglich  werden  wir den Beitrag in unsere AMOK-Reihe aufnehmen. Wir stellen
  21. zwar keine Ansprüche an die Genialität der Programme, damit Ihr Beitrag eine
  22. Chance   hat,   veröffentlicht   zu  werden,  sollten  Sie  aber  die  unten
  23. aufgeführten  Punkte beachten. Damit gewährleistet ist, daß Ihre PD-Software
  24. auch wirklich brauchbar ist.
  25.  
  26.  
  27. 1) Kriterien
  28.  
  29. Wie  schon  erwähnt stellen wir keine Anforderungen an das, was ein Programm
  30. besonderes  kann.  Das  was  es  kann,  soll  es  aber  sinnvoll und korrekt
  31. ausführen. Ein simples aber nützliches Modul hat, auch wenn es noch so banal
  32. ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt, das an
  33. sich genial ist, aber ständig guru-meditiert.
  34.  
  35.  
  36. 2) AMOK Anforderungen
  37.  
  38. Die   Folgenden   Punkte   sind   verbindlich  und  von  jedem  AMOK-Beitrag
  39. einzuhalten:
  40.  
  41. * Zu jedem Modul(-packet) gehört eine Dokumentation. Ohne Dokumentation sind
  42.   die Module für andere unbrauchbar. Es gibt auf den AMOK-Disketten folgende
  43.   Formen der Dokumentation:
  44.  
  45.     -  Dokumentation  im Klartext in einer extra Datei mit der Endung ".dok"
  46.        (für deutsche Dokumentation) oder ".doc" (für die englische)
  47.  
  48.     - stichwortartige  Kurzbeschreibung  der  Prozeduren im Definitionsmodul
  49.       Diese Form der Dokumentation ist in "HeaderInfo" genauer beschrieben.
  50.  
  51.   Die Dokumentation sollte mindestens diese Informationen beinhalten:
  52.     - Bedeutung und Auswirkung der Prozedurparameter
  53.     - Funktion und Verwendungszweck der Prozeduren
  54.     - Bedeutung der Rückgabewerte der Prozeduren
  55.     - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen
  56.     - Hinweise auf mögliche Fehler (soweit bekannt)
  57.     - Angaben über eventuelle Einschränkungen oder Warnungen
  58.  
  59.   Wenn möglich sollte die Dokumentation nur in reinem ASCII-Code geschrieben
  60.   werden. (MuchMore- und copy-to-prt:-verträglich)
  61.  
  62. * Ebenfalls  sehr  wichtig  sind  die  Files  mit  einer  Produktinformation
  63.   (".product-info") nach den Spezifikationen der FishROM Database  Draft  #5
  64.   (oder höher, Änderungen siehe unten!). Ohne  das  hat  ein  Programm  kaum
  65.   eine Chance, auf AMOK veröffentlicht zu werden.
  66.  
  67.   Eine  Beschreibung  des  File-Formats  befindet  sich  auf  der  Disk. Als
  68.   Beschreibungsprache sollte Englisch verwendet werden. Aber schreibt lieber
  69.   eine  deutsche  Beschreibung  als  gar  keine!  Das vorgegebene Format muß
  70.   unbedingt  eingehalten  werden,  es  gibt  allerdings  folgende Änderungen
  71.   gegenüber dem Draft #6 von Fish:
  72.  
  73.   --> .reference  ist  für  AMOK-Files  ebenfalls  nicht  optional,  und muß
  74.       angegeben  werden  wenn es eine ältere Version gibt, damit man auf die
  75.       letzte (alte) Version verweisen kann.
  76.  
  77.       Bsp.:
  78.       --------schnipp--------
  79.       .reference
  80.       AMOK#99:DrawA5000/
  81.       1.0
  82.       --------schnapp--------
  83.  
  84.       Erzeugt z.B. "Update zu Version 1.0 auf AMOK #99"
  85.  
  86.   --> Source   ist   nicht  optional.  Dieser  String  wird  nach  folgenden
  87.       Schlüsselwörtern durchsucht: Oberon, Modula, M2, Arexx. Entsprechendes
  88.       erscheint dann in Klammern hinter dem Namen. Bsp.:
  89.  
  90.       DrawA5000 1.1 (Oberon/Modula/Arexx)
  91.  
  92.   --> Wir haben ein neues Feld eingeführt: .beschreibung
  93.       Es sollte das selbe enthalten wie .description, nur halt auf  deutsch.
  94.       Aus diesem Feld generieren wir das File 'Inhalt'.
  95.  
  96.   Das Ganze hat folgende Vorteile:
  97.  
  98.   - nur EINE Beschreibung für AMOK und Fish
  99.   - KingFisher kann damit auch AMOK-Disks verwalten
  100.   - Wir können das Erstellen der contents-files automatisieren
  101.  
  102.   Beispiele  finden  sich  ab sofort auf jeder AMOK-Disk (bis 103 allerdings
  103.   meist als Mini-info, da von uns zusammengestellt).
  104.  
  105. *  Der  Source-Code  sollte  den Modulen immer beigefügt werden. Schließlich
  106.    sollen  andere  Programmierer  aus  Ihrem  Programm  etwas lernen können.
  107.    Außerdem  ist  es somit möglich, eventuelle Fehler zu verbessern oder das
  108.    Programm  an  eigene  Bedürfnisse anzupassen. Als Ausnahmen sind folgende
  109.    zulässig:
  110.  
  111.     - das  Programm  ist wirklich ausgesprochen genial und gehört eigentlich
  112.       patentiert (es muß natürlich absolut fehlerfrei sein)
  113.     - die  Module  sind  Teile  eines  von  Ihnen  kommerziell  vertriebenen
  114.       Programms, und Sie wollen nicht, daß jemand Einblick erhält
  115.     - Ihr  Programmierstil  ist  so  schlecht  und  Ihre  Methoden so haar-
  116.       sträubend,  daß  Sie  den  Source-Code  niemandem  zumuten wollen (In
  117.       diesem  Fall  sollten  Sie  sich  allerdings  Überlegen, ob Sie nicht
  118.       lieber C oder Assembler programmieren wollen)
  119.  
  120. * Definitions  und  Implementationsmodul  sollten  unseren  Modulkopf (siehe
  121.   "HeaderInfo")  beinhalten.   Dieser  ist  zur  leichteren  Verwaltung  der
  122.   inzwischen    mehrere    Megabyte   umfassenden    AMOK-Softwarebibliothek
  123.   notwendig. Haltet  Euch an unsere Formatvorgaben in "HeaderInfo".
  124.  
  125. * Alle  Dateien und Unterdirectories sollen Icons haben, so  daß Sie von der
  126.   Workbench  aus  leicht  zugänglich  sind.   Das Standardprogramm  (Default
  127.   Tool)  von  Textdateien  (Source  und Dokumentation) muß auf ":c/MuchMore"
  128.   eingestellt sein.
  129.  
  130.  
  131. 3) AMOK Vereinbarungen
  132.  
  133. Es wird gebeten, auch auf folgendes zu achten:
  134.  
  135. * Sollten  zum  Compilieren  eines  Moduls  noch andere nicht standardmäßige
  136.   Module  benötigt  werden,  sollten  diese  mitgeliefert  werden. Dabei ist
  137.   darauf zu achten, daß die sym-Schlüssel stimmen, d.h. alles mit der selben
  138.   Version der Definitionsmodule compiliert wurde. Existieren von imortierten
  139.   Modulen  mehrere  Versionen,  dann  ist  anzugeben,  welche benötigt wird.
  140.   (Vermerk :Imports.)
  141.  
  142. * Im  Source-Code  und  in  der  Dokumentation  sollte  man wenn möglich die
  143.   Zeilenlänge  auf  70  bis  75  Zeichen  begrenzen.  MuchMore  und  M2Emacs
  144.   akzeptieren  zwar  80  Zeichen,  viele möchten jedoch sicherlich die Texte
  145.   ausdrucken, und da ist ein Rand ganz nützlich.
  146.  
  147. * Prozedur-,   Variablen-,   Konstanten-   und    Typenbezeichner    sollten
  148.   vorzugsweise  englisch  sein,  ebenso  die Kurzbeschreibung der Prozeduren
  149.   (siehe  AMOK#7,  ProgInfo/StandardIDs). Wenigstens sollte man Englisch und
  150.   Deutsch   nicht  mischen.  Deutsche  Dokumentation  sollte  nicht  fehlen,
  151.   englische ist freiwillig.
  152.  
  153. * Kleine  Demoprogramme  dienen  der leichteren Verständnis und dem besseren
  154.   Einarbeiten  in  die  Funktionen  eines  Moduls.  Oft sind Testmodule oder
  155.   sonstige  Beispielanwendungen  als Nebenprodukte eigener Programme sowieso
  156.   vorhanden.
  157.  
  158. * Seien Sie fair gegenüber anderen Programmierern. PD heißt noch lange nicht
  159.   "Software-Freiwild".   Wenn  Sie  Programmteile  von  anderen  übernehmen,
  160.   erwähnen  Sie  den  Autor  bitte im Modulkopf oder in Kommentarzeilen. Für
  161.   eine  kommerzielle  Nutzung  brauchen  Sie  die Schriftliche Erlaubnis des
  162.   jewiligen Autors. Denken Sie bitte auch an eventuelle Shareware-Gebühren.
  163.  
  164.  
  165. 4) Zum Thema korrekte Programme
  166.  
  167. Die  folgenden  Anweisungen gelten nicht speziell für AMOK-Disketten sondern
  168. sollten  von allen Programmierern beachtet werden. Wenn diese Punkte für Sie
  169. noch  nicht  selbstverständlich  sind,  empfehlen  wir Ihnen DRINGENDST Ihre
  170. Programme in Zukunft dementsprechend auszulegen.
  171.  
  172. * Alle  Programme  müssen  entsprechend  den  Richtlinien  der  ROM  Kernal
  173.   Reference Manuals programmiert sein.
  174.  
  175.   - Amiga User Interface Style Guide ISBN 0-201-57757-7, Addison-Wesley
  176.   - Amiga ROM Kernel Manual: Libraries ISBN 0-201-56774-1, Addison-Wesley
  177.   - Amiga ROM Kernel Manual: Includes & Autodocs ISBN 0-201-56773-3, A.-W.
  178.   - Amiga ROM Kernel Manual: Devices ISBN 0-201-56775-X, Addison-Wesley
  179.   - Amiga Hardware Manual ISBN 0-201-56776-8, Addison-Wesley
  180.   - The Amiga Guru Book, Ralph Babel, Eigenverlag
  181.  
  182.   - Native Developer's Update 3.1 (Examples, Debugging-Tools, Includes,
  183.                                    Autodocs)
  184.  
  185. * Alle  Programme  sollten  auf  korrektem  Weg verlassen werden können, das
  186.   heißt,  ohne  neu  starten  zu müssen, und so, daß uneingeschränkt weiter-
  187.   gearbeitet  werden  kann.  Außerdem  sollen  Sie  alle  Betriebsmittel und
  188.   Resourcen  an  das  System  zurückgeben  (Speicher  deallozieren, Fenster,
  189.   Screens und Files schließen).
  190.  
  191. * Programme  sollten  sich nicht so verhalten, als wären Sie die einzigen im
  192.   System,  sondern  auf  das  Multitasking und seine Restriktionen Rücksicht
  193.   nehmen (z.B. gegenseitiger Ausschluß beim Zugriff auf System- strukturen).
  194.  
  195. * Programme  sollen  sich  gegenüber  dem  Benutzer logisch und bei Fehlein-
  196.   gaben robust verhalten.
  197.  
  198. * Man  sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen, die
  199.   man  anfordert. Programme sollen sich definiert verhalten, wenn z.B. Files
  200.   nicht  geöffnet werden können, oder nicht mehr genügend Speicher vorhanden
  201.   ist.
  202.  
  203. * Die  Benutzerschnittstelle  soll  den beim AMIGA allgemein üblichen Richt-
  204.   linien entsprechen (siehe Amiga User Inteface Style Guide).
  205.  
  206. * Programme   sollten   wenn  möglich  keine  spezielle  Gerätekonfiguration
  207.   vorraussetzen.
  208.  
  209. * Besonders  für  die Entwicklung zukünftiger Bibliotheksmodule ist wichtig,
  210.   daß die Prozeduren reentrant sind, falls es sinnvoll ist, sie von mehreren
  211.   Tasks  aus  gleichzeitig  zu  benutzen (es ist in Modula ja nicht möglich,
  212.   Module zweimal zu importieren).
  213.  
  214. --- Viel Spaß
  215.